{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "4e0042ce",
   "metadata": {},
   "source": [
    "# Flagging holidays\n",
    "\n",
    "[Feature Engineering for Time Series Forecasting](https://www.trainindata.com/p/feature-engineering-for-forecasting)\n",
    "\n",
    "In this notebook, we will discuss 3 methods to flag holidays in our data:\n",
    "\n",
    "- Manually\n",
    "- Using the `holidays` package\n",
    "- Using pandas\n",
    "\n",
    "We will use the **online_retail dataset**, which you can obtain following the instructions in the notebook: `02-create-online-retail-II-datasets` in the **01-Create-Datasets** folder."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "edb15f46",
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "import pandas as pd\n",
    "import matplotlib.pyplot as plt"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7e9ceba3",
   "metadata": {},
   "source": [
    "## Load data and prepare data"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "51cfe4fa",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>quantity</th>\n",
       "      <th>revenue</th>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>invoice_date</th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>2009-12-01</th>\n",
       "      <td>21050</td>\n",
       "      <td>37366.32</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2009-12-02</th>\n",
       "      <td>25248</td>\n",
       "      <td>45644.67</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2009-12-03</th>\n",
       "      <td>47485</td>\n",
       "      <td>66327.53</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2009-12-04</th>\n",
       "      <td>18607</td>\n",
       "      <td>31448.44</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2009-12-05</th>\n",
       "      <td>4722</td>\n",
       "      <td>9042.36</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "              quantity   revenue\n",
       "invoice_date                    \n",
       "2009-12-01       21050  37366.32\n",
       "2009-12-02       25248  45644.67\n",
       "2009-12-03       47485  66327.53\n",
       "2009-12-04       18607  31448.44\n",
       "2009-12-05        4722   9042.36"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# File path:\n",
    "file = \"../Datasets/online_retail_II.xlsx\"\n",
    "\n",
    "# The data is provided as two sheets in a single Excel file.\n",
    "# Each sheet contains a different time period.\n",
    "# Load both and join them into a single dataframe\n",
    "# as shown below:\n",
    "\n",
    "df = pd.read_excel(file, sheet_name=\"Year 2009-2010\")\n",
    "# df_2 = pd.read_excel(file, sheet_name=\"Year 2010-2011\")\n",
    "\n",
    "# df = pd.concat([df_1, df_2])\n",
    "\n",
    "# Rename columns\n",
    "df.columns = [\n",
    "    \"invoice\",\n",
    "    \"stock_code\",\n",
    "    \"description\",\n",
    "    \"quantity\",\n",
    "    \"invoice_date\",\n",
    "    \"price\",\n",
    "    \"customer_id\",\n",
    "    \"country\",\n",
    "]\n",
    "\n",
    "# just UK\n",
    "df = df[df[\"country\"] == \"United Kingdom\"]\n",
    "\n",
    "# add revenue variable\n",
    "df[\"revenue\"] = df[\"quantity\"] * df[\"price\"]\n",
    "\n",
    "# remove cancelled orders and missing customer ids\n",
    "df[\"is_cancelled\"] = df[\"invoice\"].apply(lambda x: str(x)[0] == \"C\")\n",
    "mask = (~df[\"customer_id\"].isnull()) & (~df[\"is_cancelled\"])\n",
    "\n",
    "# resample for total daily revenue\n",
    "df = (\n",
    "    df.loc[mask, [\"invoice_date\", \"quantity\", \"revenue\"]]\n",
    "    .resample(\"D\", on=\"invoice_date\")\n",
    "    .sum()\n",
    ")\n",
    "\n",
    "df.head()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "id": "b793d947-7ff3-4d48-9521-f1ffe7576922",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>quantity</th>\n",
       "      <th>revenue</th>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>invoice_date</th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>2010-11-22</th>\n",
       "      <td>14541</td>\n",
       "      <td>27730.36</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2010-11-23</th>\n",
       "      <td>22915</td>\n",
       "      <td>46286.36</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2010-11-24</th>\n",
       "      <td>23266</td>\n",
       "      <td>40106.34</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2010-11-25</th>\n",
       "      <td>36443</td>\n",
       "      <td>66040.90</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2010-11-26</th>\n",
       "      <td>11107</td>\n",
       "      <td>20950.99</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "              quantity   revenue\n",
       "invoice_date                    \n",
       "2010-11-22       14541  27730.36\n",
       "2010-11-23       22915  46286.36\n",
       "2010-11-24       23266  40106.34\n",
       "2010-11-25       36443  66040.90\n",
       "2010-11-26       11107  20950.99"
      ]
     },
     "execution_count": 12,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "df.loc[\"2010-11-22\":\"2010-11-26\"]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "61ab2510",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<AxesSubplot:xlabel='invoice_date'>"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    },
    {
     "data": {
      "image/png": "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\n",
      "text/plain": [
       "<Figure size 1440x360 with 1 Axes>"
      ]
     },
     "metadata": {
      "needs_background": "light"
     },
     "output_type": "display_data"
    }
   ],
   "source": [
    "# plot time series\n",
    "\n",
    "df[\"revenue\"].plot(figsize=(20,5))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "76168c4c",
   "metadata": {},
   "source": [
    "## Flag specific dates - manually\n",
    "\n",
    "First, we create a list with the specific holidays we want to highlight, for example Black Fridays. And then we add an indicator to flag those dates in our dataset.\n",
    "\n",
    "- Pros: Easy\n",
    "- Con: We need to enter manually each date, for each year ==> impractical"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "id": "be9249ce",
   "metadata": {},
   "outputs": [],
   "source": [
    "import datetime"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "id": "b8530b68",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Black Friday dates in 2010 and 2011\n",
    "black_friday = [datetime.date(2010, 11, 26), \n",
    "                datetime.date(2011, 11, 25)]\n",
    "\n",
    "\n",
    "# Create dummy variable for Black Friday\n",
    "df[\"is_black_friday\"] = np.where(df.index.isin(black_friday), 1, 0)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "id": "bb18f508-9def-4252-a6be-0a33763deaaf",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>quantity</th>\n",
       "      <th>revenue</th>\n",
       "      <th>is_black_friday</th>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>invoice_date</th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>2010-11-22</th>\n",
       "      <td>14541</td>\n",
       "      <td>27730.36</td>\n",
       "      <td>0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2010-11-23</th>\n",
       "      <td>22915</td>\n",
       "      <td>46286.36</td>\n",
       "      <td>0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2010-11-24</th>\n",
       "      <td>23266</td>\n",
       "      <td>40106.34</td>\n",
       "      <td>0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2010-11-25</th>\n",
       "      <td>36443</td>\n",
       "      <td>66040.90</td>\n",
       "      <td>0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2010-11-26</th>\n",
       "      <td>11107</td>\n",
       "      <td>20950.99</td>\n",
       "      <td>1</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "              quantity   revenue  is_black_friday\n",
       "invoice_date                                     \n",
       "2010-11-22       14541  27730.36                0\n",
       "2010-11-23       22915  46286.36                0\n",
       "2010-11-24       23266  40106.34                0\n",
       "2010-11-25       36443  66040.90                0\n",
       "2010-11-26       11107  20950.99                1"
      ]
     },
     "execution_count": 25,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "df.loc[\"2010-11-22\":\"2010-11-26\"]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "id": "f8ed3693-98c5-44ac-b29a-735b49210b2b",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "130 µs ± 8.41 µs per loop (mean ± std. dev. of 7 runs, 10,000 loops each)\n"
     ]
    }
   ],
   "source": [
    "%%timeit\n",
    "np.where(df.index.isin(black_friday), 1, 0)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "f38f5218",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>quantity</th>\n",
       "      <th>revenue</th>\n",
       "      <th>holidays</th>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>invoice_date</th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>2010-11-26</th>\n",
       "      <td>11107</td>\n",
       "      <td>20950.99</td>\n",
       "      <td>1</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2011-11-25</th>\n",
       "      <td>25197</td>\n",
       "      <td>22978.56</td>\n",
       "      <td>1</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "              quantity   revenue  holidays\n",
       "invoice_date                              \n",
       "2010-11-26       11107  20950.99         1\n",
       "2011-11-25       25197  22978.56         1"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# flag Black Fridays\n",
    "\n",
    "df[\"holidays\"] = np.where(df.index.isin(black_friday),1,0)\n",
    "\n",
    "df[df[\"holidays\"]==1]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "id": "3a397361",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Int64Index([4, 4], dtype='int64', name='invoice_date')"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# let's double check that it was Friday\n",
    "\n",
    "df[df[\"holidays\"]==1].index.weekday"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e07a4f82",
   "metadata": {},
   "source": [
    "## With the holidays library\n",
    "\n",
    "- https://pypi.org/project/holidays/\n",
    "- https://python-holidays.readthedocs.io/en/latest/\n",
    "\n",
    "**Pros**: contains the holidays from several countries."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "id": "2ef127a4",
   "metadata": {},
   "outputs": [],
   "source": [
    "import holidays"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "id": "7b9c52c0",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "holidays.country_holidays('GB', subdiv='UK')"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "uk_holidays = holidays.UK()\n",
    "\n",
    "uk_holidays"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "id": "93c59989",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "2010-01-01 New Year's Day\n",
      "2010-01-02 New Year Holiday [Scotland]\n",
      "2010-01-04 New Year Holiday [Scotland] (Observed)\n",
      "2010-03-17 St. Patrick's Day [Northern Ireland]\n",
      "2010-04-02 Good Friday\n",
      "2010-04-05 Easter Monday [England/Wales/Northern Ireland]\n",
      "2010-05-03 May Day\n",
      "2010-05-31 Spring Bank Holiday\n",
      "2010-07-12 Battle of the Boyne [Northern Ireland]\n",
      "2010-08-02 Summer Bank Holiday [Scotland]\n",
      "2010-08-30 Late Summer Bank Holiday [England/Wales/Northern Ireland]\n",
      "2010-11-30 St. Andrew's Day [Scotland]\n",
      "2010-12-25 Christmas Day\n",
      "2010-12-26 Boxing Day\n",
      "2010-12-27 Christmas Day (Observed)\n",
      "2010-12-28 Boxing Day (Observed)\n",
      "2011-01-01 New Year's Day\n",
      "2011-01-02 New Year Holiday [Scotland]\n",
      "2011-01-03 New Year's Day (Observed)\n",
      "2011-01-04 New Year Holiday [Scotland] (Observed)\n",
      "2011-03-17 St. Patrick's Day [Northern Ireland]\n",
      "2011-04-22 Good Friday\n",
      "2011-04-25 Easter Monday [England/Wales/Northern Ireland]\n",
      "2011-04-29 Wedding of William and Catherine\n",
      "2011-05-02 May Day\n",
      "2011-05-30 Spring Bank Holiday\n",
      "2011-07-12 Battle of the Boyne [Northern Ireland]\n",
      "2011-08-01 Summer Bank Holiday [Scotland]\n",
      "2011-08-29 Late Summer Bank Holiday [England/Wales/Northern Ireland]\n",
      "2011-11-30 St. Andrew's Day [Scotland]\n",
      "2011-12-25 Christmas Day\n",
      "2011-12-26 Boxing Day\n",
      "2011-12-27 Christmas Day (Observed)\n"
     ]
    }
   ],
   "source": [
    "# let's check the holidays available for the UK\n",
    "\n",
    "for date, name in sorted(holidays.UK(subdiv='UK', years=[2010,2011]).items()):\n",
    "    print(date, name)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "id": "1c577992",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[datetime.date(2010, 1, 1),\n",
       " datetime.date(2010, 1, 2),\n",
       " datetime.date(2010, 1, 4),\n",
       " datetime.date(2010, 3, 17),\n",
       " datetime.date(2010, 7, 12),\n",
       " datetime.date(2010, 8, 2),\n",
       " datetime.date(2010, 11, 30),\n",
       " datetime.date(2010, 12, 25),\n",
       " datetime.date(2010, 12, 27),\n",
       " datetime.date(2010, 4, 2),\n",
       " datetime.date(2010, 4, 5),\n",
       " datetime.date(2010, 5, 3),\n",
       " datetime.date(2010, 5, 31),\n",
       " datetime.date(2010, 8, 30),\n",
       " datetime.date(2010, 12, 26),\n",
       " datetime.date(2010, 12, 28),\n",
       " datetime.date(2011, 1, 1),\n",
       " datetime.date(2011, 1, 3),\n",
       " datetime.date(2011, 1, 2),\n",
       " datetime.date(2011, 1, 4),\n",
       " datetime.date(2011, 3, 17),\n",
       " datetime.date(2011, 7, 12),\n",
       " datetime.date(2011, 8, 1),\n",
       " datetime.date(2011, 11, 30),\n",
       " datetime.date(2011, 12, 25),\n",
       " datetime.date(2011, 12, 27),\n",
       " datetime.date(2011, 4, 22),\n",
       " datetime.date(2011, 4, 25),\n",
       " datetime.date(2011, 5, 2),\n",
       " datetime.date(2011, 5, 30),\n",
       " datetime.date(2011, 8, 29),\n",
       " datetime.date(2011, 12, 26),\n",
       " datetime.date(2011, 4, 29)]"
      ]
     },
     "execution_count": 11,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# let's capture the dates in a list:\n",
    "\n",
    "uk_holidays = [items[0] for items in holidays.UK(subdiv='UK', years=[2010,2011]).items()]\n",
    "\n",
    "uk_holidays"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "id": "88e0e189",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>quantity</th>\n",
       "      <th>revenue</th>\n",
       "      <th>holidays</th>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>invoice_date</th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>2010-01-01</th>\n",
       "      <td>0</td>\n",
       "      <td>0.00</td>\n",
       "      <td>1</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2010-01-02</th>\n",
       "      <td>0</td>\n",
       "      <td>0.00</td>\n",
       "      <td>1</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2010-01-04</th>\n",
       "      <td>10601</td>\n",
       "      <td>13450.54</td>\n",
       "      <td>1</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2010-03-17</th>\n",
       "      <td>13010</td>\n",
       "      <td>19504.10</td>\n",
       "      <td>1</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2010-04-02</th>\n",
       "      <td>0</td>\n",
       "      <td>0.00</td>\n",
       "      <td>1</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2010-04-05</th>\n",
       "      <td>0</td>\n",
       "      <td>0.00</td>\n",
       "      <td>1</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2010-05-03</th>\n",
       "      <td>0</td>\n",
       "      <td>0.00</td>\n",
       "      <td>1</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2010-05-31</th>\n",
       "      <td>0</td>\n",
       "      <td>0.00</td>\n",
       "      <td>1</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2010-07-12</th>\n",
       "      <td>8234</td>\n",
       "      <td>14555.73</td>\n",
       "      <td>1</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2010-08-02</th>\n",
       "      <td>11753</td>\n",
       "      <td>25839.08</td>\n",
       "      <td>1</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2010-08-30</th>\n",
       "      <td>0</td>\n",
       "      <td>0.00</td>\n",
       "      <td>1</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2010-11-30</th>\n",
       "      <td>19481</td>\n",
       "      <td>40759.92</td>\n",
       "      <td>1</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2010-12-25</th>\n",
       "      <td>0</td>\n",
       "      <td>0.00</td>\n",
       "      <td>1</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2010-12-26</th>\n",
       "      <td>0</td>\n",
       "      <td>0.00</td>\n",
       "      <td>1</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2010-12-27</th>\n",
       "      <td>0</td>\n",
       "      <td>0.00</td>\n",
       "      <td>1</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2010-12-28</th>\n",
       "      <td>0</td>\n",
       "      <td>0.00</td>\n",
       "      <td>1</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2011-01-01</th>\n",
       "      <td>0</td>\n",
       "      <td>0.00</td>\n",
       "      <td>1</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2011-01-02</th>\n",
       "      <td>0</td>\n",
       "      <td>0.00</td>\n",
       "      <td>1</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2011-01-03</th>\n",
       "      <td>0</td>\n",
       "      <td>0.00</td>\n",
       "      <td>1</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2011-01-04</th>\n",
       "      <td>6666</td>\n",
       "      <td>11577.90</td>\n",
       "      <td>1</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2011-03-17</th>\n",
       "      <td>16490</td>\n",
       "      <td>25166.96</td>\n",
       "      <td>1</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2011-04-22</th>\n",
       "      <td>0</td>\n",
       "      <td>0.00</td>\n",
       "      <td>1</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2011-04-25</th>\n",
       "      <td>0</td>\n",
       "      <td>0.00</td>\n",
       "      <td>1</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2011-04-29</th>\n",
       "      <td>0</td>\n",
       "      <td>0.00</td>\n",
       "      <td>1</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2011-05-02</th>\n",
       "      <td>0</td>\n",
       "      <td>0.00</td>\n",
       "      <td>1</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2011-05-30</th>\n",
       "      <td>0</td>\n",
       "      <td>0.00</td>\n",
       "      <td>1</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2011-07-12</th>\n",
       "      <td>10256</td>\n",
       "      <td>15680.52</td>\n",
       "      <td>1</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2011-08-01</th>\n",
       "      <td>10486</td>\n",
       "      <td>17959.66</td>\n",
       "      <td>1</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2011-08-29</th>\n",
       "      <td>0</td>\n",
       "      <td>0.00</td>\n",
       "      <td>1</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2011-11-30</th>\n",
       "      <td>18911</td>\n",
       "      <td>31900.70</td>\n",
       "      <td>1</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "              quantity   revenue  holidays\n",
       "invoice_date                              \n",
       "2010-01-01           0      0.00         1\n",
       "2010-01-02           0      0.00         1\n",
       "2010-01-04       10601  13450.54         1\n",
       "2010-03-17       13010  19504.10         1\n",
       "2010-04-02           0      0.00         1\n",
       "2010-04-05           0      0.00         1\n",
       "2010-05-03           0      0.00         1\n",
       "2010-05-31           0      0.00         1\n",
       "2010-07-12        8234  14555.73         1\n",
       "2010-08-02       11753  25839.08         1\n",
       "2010-08-30           0      0.00         1\n",
       "2010-11-30       19481  40759.92         1\n",
       "2010-12-25           0      0.00         1\n",
       "2010-12-26           0      0.00         1\n",
       "2010-12-27           0      0.00         1\n",
       "2010-12-28           0      0.00         1\n",
       "2011-01-01           0      0.00         1\n",
       "2011-01-02           0      0.00         1\n",
       "2011-01-03           0      0.00         1\n",
       "2011-01-04        6666  11577.90         1\n",
       "2011-03-17       16490  25166.96         1\n",
       "2011-04-22           0      0.00         1\n",
       "2011-04-25           0      0.00         1\n",
       "2011-04-29           0      0.00         1\n",
       "2011-05-02           0      0.00         1\n",
       "2011-05-30           0      0.00         1\n",
       "2011-07-12       10256  15680.52         1\n",
       "2011-08-01       10486  17959.66         1\n",
       "2011-08-29           0      0.00         1\n",
       "2011-11-30       18911  31900.70         1"
      ]
     },
     "execution_count": 12,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# flag holidays\n",
    "\n",
    "df[\"holidays\"] = np.where(df.index.isin(uk_holidays),1,0)\n",
    "\n",
    "df[df[\"holidays\"]==1]"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f6c9b6a7",
   "metadata": {},
   "source": [
    "Check for other countries in the documentation: https://python-holidays.readthedocs.io/en/latest/index.html#available-countries"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1a8bed59",
   "metadata": {},
   "source": [
    "## With pandas\n",
    "\n",
    "Pandas supports the US Federal Holidays by default. For any other country, we need to create a special calendar. \n",
    "\n",
    "Let's create a calendar for the UK.\n",
    "\n",
    "### Rules\n",
    "\n",
    "Most holidays occur on a certain date, but are observed on a different day if they fall on a weekend. With this information, we can create rules to automatically assign the holidays to the correct date for every year.\n",
    "\n",
    "**Pandas supports the following default rules:**\n",
    "\n",
    "- nearest_workday ==> move Saturday to Friday and Sunday to Monday\n",
    "- sunday_to_monday ==> move Sunday to following Monday\n",
    "- next_monday_or_tuesday ==> move Saturday to Monday and Sunday/Monday to Tuesday\n",
    "- previous_friday ==> move Saturday and Sunday to previous Friday\n",
    "- next_monday ==> move Saturday and Sunday to following Monday\n",
    "\n",
    "It also allows us to speficy a day in a month, for example, first Monday or 3rd Friday through the MO, TU, WE, TH, FR, SA, SU functions."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "id": "1232b17c",
   "metadata": {},
   "outputs": [],
   "source": [
    "from pandas.tseries.holiday import (\n",
    "    Holiday,\n",
    "    AbstractHolidayCalendar, # provides all the necessary methods to return a list of holidays\n",
    "    nearest_workday, # rule\n",
    "    GoodFriday,\n",
    "    EasterMonday,\n",
    "    MO, # rule\n",
    "    FR, # rule\n",
    ")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "id": "b0b07d37",
   "metadata": {},
   "outputs": [],
   "source": [
    "# let's create our calendar\n",
    "\n",
    "class UKHolidays(AbstractHolidayCalendar):\n",
    "    rules = [\n",
    "        GoodFriday,\n",
    "        \n",
    "        EasterMonday,\n",
    "        \n",
    "        Holiday(\"New Year's Day\", month=1, day=1),\n",
    "        \n",
    "        Holiday(\"May Day\", month=5, day=1, offset=pd.DateOffset(\n",
    "            weekday=MO(1))),  # first monday\n",
    "        \n",
    "        Holiday(\"Spring Bank Holiday\", month=5, day=31,\n",
    "                offset=pd.DateOffset(weekday=MO(-1))),  # last monday\n",
    "        \n",
    "        Holiday(\"Black Fridays\", month=11, day=25,\n",
    "                offset=pd.DateOffset(weekday=FR(-1))), # third friday\n",
    "        \n",
    "        Holiday(\"Company's birthday\", month=8,\n",
    "                day=29, observance=nearest_workday),\n",
    "        \n",
    "    ]"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e9c65a5f",
   "metadata": {},
   "source": [
    "For more information about how MO, TU, WE, TH, FR, SA and SU work, check the library [relativedelta](https://dateutil.readthedocs.io/en/stable/relativedelta.html#dateutil.relativedelta.relativedelta).\n",
    "\n",
    "**weekday:**\n",
    "\n",
    "One of the weekday instances (MO, TU, etc) available in the\n",
    "relativedelta module. These instances may receive a parameter N,\n",
    "specifying the Nth weekday, which could be positive or negative\n",
    "(like MO(+1) or MO(-2)). Not specifying it is the same as specifying\n",
    "+1. You can also use an integer, where 0=MO. This argument is always\n",
    "relative e.g. if the calculated date is already Monday, using MO(1)\n",
    "or MO(-1) won't change the day. To effectively make it absolute, use\n",
    "it in combination with the day argument (e.g. day=1, MO(1) for first\n",
    "Monday of the month)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "id": "1f1fbd9f",
   "metadata": {},
   "outputs": [],
   "source": [
    "# set up the calendar\n",
    "\n",
    "cal = UKHolidays()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "id": "a93659d1",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[Holiday: Good Friday (month=1, day=1, offset=[<Easter>, <-2 * Days>]),\n",
       " Holiday: Easter Monday (month=1, day=1, offset=[<Easter>, <Day>]),\n",
       " Holiday: New Year's Day (month=1, day=1, ),\n",
       " Holiday: May Day (month=5, day=1, offset=<DateOffset: weekday=MO(+1)>),\n",
       " Holiday: Spring Bank Holiday (month=5, day=31, offset=<DateOffset: weekday=MO(-1)>),\n",
       " Holiday: Black Fridays (month=11, day=25, offset=<DateOffset: weekday=FR(-1)>),\n",
       " Holiday: Company's birthday (month=8, day=29, observance=<function nearest_workday at 0x00000227772B95A0>)]"
      ]
     },
     "execution_count": 16,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "cal.rules"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "id": "091d8cea",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "DatetimeIndex(['2010-11-19', '2011-01-01', '2011-04-22', '2011-04-25',\n",
       "               '2011-05-02', '2011-05-30', '2011-08-29', '2011-11-25',\n",
       "               '2012-01-01'],\n",
       "              dtype='datetime64[ns]', freq=None)"
      ]
     },
     "execution_count": 17,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# find the holiday dates in a certain period of time\n",
    "\n",
    "uk_holidays = cal.holidays(datetime.datetime(2010, 11, 1), datetime.datetime(2012, 3, 31))\n",
    "\n",
    "uk_holidays"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "id": "1e80d878",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>quantity</th>\n",
       "      <th>revenue</th>\n",
       "      <th>holidays</th>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>invoice_date</th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>2010-11-19</th>\n",
       "      <td>18837</td>\n",
       "      <td>30229.20</td>\n",
       "      <td>1</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2011-01-01</th>\n",
       "      <td>0</td>\n",
       "      <td>0.00</td>\n",
       "      <td>1</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2011-04-22</th>\n",
       "      <td>0</td>\n",
       "      <td>0.00</td>\n",
       "      <td>1</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2011-04-25</th>\n",
       "      <td>0</td>\n",
       "      <td>0.00</td>\n",
       "      <td>1</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2011-05-02</th>\n",
       "      <td>0</td>\n",
       "      <td>0.00</td>\n",
       "      <td>1</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2011-05-30</th>\n",
       "      <td>0</td>\n",
       "      <td>0.00</td>\n",
       "      <td>1</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2011-08-29</th>\n",
       "      <td>0</td>\n",
       "      <td>0.00</td>\n",
       "      <td>1</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2011-11-25</th>\n",
       "      <td>25197</td>\n",
       "      <td>22978.56</td>\n",
       "      <td>1</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "              quantity   revenue  holidays\n",
       "invoice_date                              \n",
       "2010-11-19       18837  30229.20         1\n",
       "2011-01-01           0      0.00         1\n",
       "2011-04-22           0      0.00         1\n",
       "2011-04-25           0      0.00         1\n",
       "2011-05-02           0      0.00         1\n",
       "2011-05-30           0      0.00         1\n",
       "2011-08-29           0      0.00         1\n",
       "2011-11-25       25197  22978.56         1"
      ]
     },
     "execution_count": 18,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# flag holidays\n",
    "\n",
    "df[\"holidays\"] = np.where(df.index.isin(uk_holidays),1,0)\n",
    "\n",
    "df[df[\"holidays\"]==1]"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4f41cd92",
   "metadata": {},
   "source": [
    "I have to say, I am not amazed by the documentation on this topic. These are the available links:\n",
    "\n",
    "- source code: https://github.com/pandas-dev/pandas/blob/main/pandas/tseries/holiday.py\n",
    "- docs: https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html?highlight=holiday#holidays-holiday-calendars"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "376ea488",
   "metadata": {},
   "source": [
    "## Default US calendar"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "id": "bd53ad56",
   "metadata": {},
   "outputs": [],
   "source": [
    "from pandas.tseries.holiday import USFederalHolidayCalendar"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "id": "b9a87690",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[Holiday: New Year's Day (month=1, day=1, observance=<function nearest_workday at 0x00000227772B95A0>),\n",
       " Holiday: Birthday of Martin Luther King, Jr. (month=1, day=1, offset=<DateOffset: weekday=MO(+3)>),\n",
       " Holiday: Washington’s Birthday (month=2, day=1, offset=<DateOffset: weekday=MO(+3)>),\n",
       " Holiday: Memorial Day (month=5, day=31, offset=<DateOffset: weekday=MO(-1)>),\n",
       " Holiday: Juneteenth National Independence Day (month=6, day=19, observance=<function nearest_workday at 0x00000227772B95A0>),\n",
       " Holiday: Independence Day (month=7, day=4, observance=<function nearest_workday at 0x00000227772B95A0>),\n",
       " Holiday: Labor Day (month=9, day=1, offset=<DateOffset: weekday=MO(+1)>),\n",
       " Holiday: Columbus Day (month=10, day=1, offset=<DateOffset: weekday=MO(+2)>),\n",
       " Holiday: Veterans Day (month=11, day=11, observance=<function nearest_workday at 0x00000227772B95A0>),\n",
       " Holiday: Thanksgiving Day (month=11, day=1, offset=<DateOffset: weekday=TH(+4)>),\n",
       " Holiday: Christmas Day (month=12, day=25, observance=<function nearest_workday at 0x00000227772B95A0>)]"
      ]
     },
     "execution_count": 20,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "cal = USFederalHolidayCalendar()\n",
    "\n",
    "cal.rules"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c2a424a6",
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.10.5"
  },
  "toc": {
   "base_numbering": 1,
   "nav_menu": {},
   "number_sections": true,
   "sideBar": true,
   "skip_h1_title": false,
   "title_cell": "Table of Contents",
   "title_sidebar": "Contents",
   "toc_cell": false,
   "toc_position": {
    "height": "calc(100% - 180px)",
    "left": "10px",
    "top": "150px",
    "width": "165px"
   },
   "toc_section_display": true,
   "toc_window_display": true
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}
